home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / AMICUS / AMICUS13.ADF / FutureSound / Example.DOC < prev    next >
Text File  |  1986-08-05  |  8KB  |  302 lines
  1.  
  2.  
  3. Interfacing Amiga Basic Programs with FutureSound sounds
  4. --------------------------------------------------------
  5.  
  6. The Amiga Basic program 'Example' is an example of using FutureSound
  7. sampled sound files in an Amiga Basic program.
  8.  
  9. The keys to the interface between the FutureSound routines and Amiga
  10. Basic are the files 'future.library', 'future.bmap' and 'exec.bmap'.
  11.  
  12. These files must be present when your program is executed.  They can
  13. be in the same directory (or drawer) where you run your Amiga Basic
  14. programs.
  15.  
  16. If you are using FutureSound files in your Amiga Basic programs
  17. alot, then copy the 'future.library' file to the LIBS: directory.
  18. This directory is called 'libs' on your Workbench disk.
  19.  
  20. In the CLI, type:
  21.  
  22. COPY DF1:BasicDemos/future.library LIBS:
  23.  
  24. Depending on your system set-up, this command may be different.
  25.  
  26. Both '.bmap' files must be present in the directory where you are
  27. running you Amiga Basic program.  The '.bmap' files coordinate
  28. the interface between Amiga Basic and the 'future.library'.
  29.  
  30. The source code to Example is included at the end of this text.
  31. It is nearly self-documenting. :-)
  32.  
  33.  
  34. 'future.library' Example AmigaDOS library
  35.  
  36. 'future.library' is an AmigaDOS library composed of some interface
  37. assembly language code, and the FutureSound C routines supplied
  38. on this disk.
  39.  
  40. The complete source to the 'future.library' is included.  If you
  41. have the Metacomco assembler and the Lattice C compiler, you can
  42. modify the 'future.library' to suit your needs.
  43.  
  44. The example Lattice C functions were converted to use only AmigaDOS
  45. level input and output, i.e., 'Open()' instead of 'fopen()'.
  46.  
  47. Also, all references to 'stdin' and 'stdout' I/O were removed.
  48. The functions were compiled with stack checking off, using the '-v'
  49. option in the 'lc2' pass of the compiler.
  50.  
  51. Also, the Lattice 'strcmp()' function was replaced with an equivalent
  52. function.
  53.  
  54. The functions were linked only with 'amiga.lib', not 'lc.lib'.
  55.  
  56. The functions do not need any startup code.  '_DOSBase' and '_SysBase'
  57. were resolved in the 'future.asm' code, the core of the library.
  58. These were the only unresolved references.  The 'future.asm' file
  59. contains more details of the interface between C and assembler.
  60.  
  61. These changes produce nearly stand-alone C functions, a necessity
  62. for inclusion in an AmigaDOS library.
  63.  
  64. Example assemble, compile and link files are included.
  65.  
  66. ----------------------------------------------------------------
  67.  
  68. (c) Copyright 1986, Applied Visions, 15 Oak Ridge Road, Medford,
  69.     Mass. 02155  (617) 488-3602.
  70.  
  71.     Text, examples, and library interface by John Foust.
  72.  
  73. -----------------------------------------------------------------
  74.  
  75. Example.MSB:
  76. A sample program using the 'future.library' in Amiga Basic.
  77.  
  78.  
  79. ' Example of Loading and Playing Sounds with the FutureSound
  80.  
  81. ' Copyright 1986 by Applied Visions
  82.  
  83. ' Applied Visions
  84. ' 15 Oak Ridge Road
  85. ' Medford, Mass. 02155
  86. ' (617) 488-3602
  87.  
  88. ' Program and text by John Foust, 22-Jun-86
  89.  
  90.  
  91. ' ATTENTION:
  92. ' Please note the files 'future.library', 'future.bmap' and 'exec.bmap'
  93. ' must be present for this program to work.
  94.  
  95.  
  96. ' We only want to declare these functions once.
  97.  
  98. IF FuncDecl = 0 THEN
  99.   DECLARE FUNCTION FSGetSize& LIBRARY
  100.   DECLARE FUNCTION FSLoadSound& LIBRARY
  101.   DECLARE FUNCTION FSPlaySound& LIBRARY
  102.   DECLARE FUNCTION FSStopSound& LIBRARY
  103.   DECLARE FUNCTION AllocMem& LIBRARY
  104.   FuncDecl = 1
  105. END IF
  106.  
  107.  
  108. ' This tells Amiga Basic we want to use these libraries.
  109. ' It will look for them in this directory and the LIBS:
  110. ' directory, which is usually on your Workbench disk.
  111.  
  112. ' The FutureSound library
  113. LIBRARY "future.library"
  114.  
  115. ' The 'exec' library for AmigaDOS functions
  116. LIBRARY "exec.library"
  117.  
  118. ' Get a sound file name from the user.
  119.  
  120. FileEntry:
  121. PRINT
  122. PRINT "Enter the full name of a sound file > ";
  123. INPUT SoundName$
  124.  
  125. PRINT
  126. PRINT "Looking for ";SoundName$
  127. PRINT
  128.  
  129. ' Add the character number ZERO to the end of the string,
  130. ' since all C strings are terminated with a zero character,
  131. ' and the library contains C functions.
  132. SoundName$ = SoundName$+CHR$(0)
  133.  
  134. 'Call the 'future.library' FSGetSize& function to get the size of
  135. 'a given sound file.  The address of the zero-terminated string 
  136. 'is sent to the function, using the Amiga Basic SADD() function.
  137.  
  138. 'If the FSGetSize& function returns zero, then it could not open
  139. 'that file for some reason.
  140. 'Chances are, they typed the name incorrectly or that file is 
  141. 'not on this disk.
  142.  
  143. SoundSize& = FSGetSize&(SADD(SoundName$))
  144.  
  145.  
  146. IF SoundSize& = 0 THEN
  147.   PRINT "That file is not present, please try another."
  148.   GOTO FileEntry
  149. END IF
  150.  
  151. PRINT "The size of that file is"; SoundSize&; "bytes."
  152.  
  153.  
  154. 'The sound file exists, so try to load it into memory.
  155. 'We must ask the operating system for memory that can be used
  156. 'by the Amiga's sound chips.  We ask for this memory to be cleared
  157. 'to all zeroes, too.
  158. 'If there is not enough memory available in this computer
  159. 'to load this sound, this function returns zero, so warn the user.
  160.  
  161. 'If we already have some memory, then free it before asking for more.
  162. 'The MemTry& would be non-zero if there was memory allocated.
  163. IF MemTry& <> 0 THEN 
  164.   GOSUB FreeUpMem
  165. END IF
  166.  
  167. 'This number, 65537, tells AmigaDOS what type of memory to allocate.
  168. 'This is MEMF_CHIP plus MEMF_CLEAR, if you know what those are.
  169. MemType& = 65537&
  170. MemTry& = AllocMem&(SoundSize&,MemType&)
  171.  
  172. 'Reset the memory size indicator
  173. MemSize& = 0
  174.  
  175. IF MemTry& = 0 THEN
  176.   PRINT "There is not enough memory to load that sound."
  177.   'Tell them how big the sound could be, using another
  178.   'exec.library' function.
  179.   MaxSize& = AvailMem&(MemType&)
  180.   PRINT "The largest sound you can load now is";
  181.   PRINT MaxSize&; "bytes in size."
  182.   PRINT "Please try again."
  183.   GOTO FileEntry
  184. END IF
  185.  
  186. 'Since the AllocMem() succeeeded, remember how much memory to free later.
  187. MemSize& = SoundSize&
  188.  
  189. 'We have allocated a large section of memory.
  190. 'Now ask the 'future.library' to load the sound.
  191. 'If this function returns zero, then something went wrong.
  192. 'If the sound loads correctly, it returns the recording rate,
  193. 'in hertz.
  194. RecRate& = FSLoadSound&(SADD(SoundName$),MemTry&)
  195.  
  196. PRINT "The sound was recorded at"; RecRate&; "hertz."
  197.  
  198. IF RecRate& = 0 THEN
  199.   PRINT "Something went wrong in loading this sound."
  200.   PRINT "Please try again."
  201.   GOSUB FreeUpMem
  202.   GOTO FileEntry
  203. END IF
  204.  
  205. 'We have loaded the sound.
  206. 'Now, we can play it.
  207. 'This function takes several arguments.
  208.  
  209. 'BufLen& represents how much of the sound to play.
  210. 'It represents the number of one-byte samples to scan per period.
  211. '  Set it to SoundSize& to play the whole sound.
  212. '  Set it to less than SoundSize& to hear only the first
  213. '    part of the sound.
  214. BufLen& = SoundSize&
  215. PRINT "The BufLen& is"; BufLen&
  216.  
  217. 'Reps& is a counter, telling how many times to repeat the sound.
  218. 'Zero means forever, 1 means once.
  219. Reps& = 1
  220. PRINT "The sound will repeat";
  221. IF Reps& = 0 THEN 
  222.   PRINT "forever."
  223. ELSE
  224.   PRINT Reps&; "times."
  225. END IF
  226.  
  227. 'Period& can be found by dividing the magic number
  228. '3579545& by the recording rate.  This should be a minimum of 124.
  229. Period& = INT(3579545& / RecRate&)
  230. PRINT "The Period is"; Period&
  231.  
  232. 'The last argument is the volume, from 0 to 64
  233. Vol& = 64
  234. PRINT "The Volume is"; Vol&
  235.  
  236.  
  237. PlayIt:
  238.  
  239. Result& = FSPlaySound&(MemTry&,BufLen&,Reps&,Period&,Vol&)
  240.  
  241. PRINT "Play this sound again?  Enter Y or N.  > ";
  242. INPUT Again$
  243.  
  244. 'Only stop a sound once!
  245. GOSUB StopIt
  246. IF Again$ = "Y" OR Again$ = "y" THEN
  247.   GOTO PlayIt
  248. END IF
  249.  
  250.  
  251. PRINT "Play another sound?  Enter Y or N.  > ";
  252. INPUT Again$
  253. IF Again$ = "Y" OR Again$ = "y" THEN
  254.   GOTO FileEntry
  255. END IF
  256.  
  257. 'Otherwise free its memory, and stop the program.
  258. GOSUB FreeUpMem
  259. GOTO EndOfIt
  260.  
  261.  
  262. FreeUpMem:
  263.  
  264. PRINT "Freeing the memory used by the sound."
  265.  
  266. 'Since we do not need this memory any more, we should
  267. 'return it to the operating system with the FreeMem function.
  268. 'Be sure not to free memory that is free already.
  269. IF MemTry& = 0 THEN GOTO ForgetIt
  270.  
  271. 'FreeMem() takes two arguments, a pointer to the memory - MemTry&
  272. 'and the size of the memory - MemSize&
  273. CALL FreeMem(MemTry&,MemSize&)
  274.  
  275. ForgetIt:
  276. RETURN
  277.  
  278.  
  279. 'Another function can stop the sound before it finishes.
  280. 'Its only argument is the value returned from FSPlaySound&
  281. 'THIS ROUTINE SHOULD BE CALLED ONLY ONCE PER CALL OF FSPlaySound !!!
  282.  
  283. StopIt:
  284.  
  285. PRINT "Halting the sound."
  286.  
  287. HaltIt& = FSStopSound&(Result&)
  288. RETURN
  289.  
  290.  
  291. 'The end of the program.
  292. EndOfIt:
  293.  
  294. PRINT "End of program."
  295.  
  296. LIBRARY CLOSE
  297.  
  298. PRINT "Library closed."
  299.  
  300. END
  301.  
  302.